From 2f78aa30249928e9e2f9f476c0ec791cf4b9da79 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 15 Sep 2010 18:37:20 -0400 Subject: [PATCH] Rename h/v-align to h/valign And adjust the getters and setters to match. Also include some documentation by Havoc Pennington about adjustment of size requests and allocations. --- docs/reference/gtk/gtk3-sections.txt | 4 + gtk/gtk.symbols | 8 +- gtk/gtksizerequest.c | 51 +++++++++++++ gtk/gtkwidget.c | 108 ++++++++++++++++----------- gtk/gtkwidget.h | 75 ++++++++++++------- tests/testadjustsize.c | 12 +-- 6 files changed, 179 insertions(+), 79 deletions(-) diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt index f204b932c4..827d81559b 100644 --- a/docs/reference/gtk/gtk3-sections.txt +++ b/docs/reference/gtk/gtk3-sections.txt @@ -4945,6 +4945,10 @@ gtk_requisition_free GtkAlign +gtk_widget_get_halign +gtk_widget_set_halign +gtk_widget_get_valign +gtk_widget_set_valign gtk_widget_get_margin_left gtk_widget_set_margin_left gtk_widget_get_margin_right diff --git a/gtk/gtk.symbols b/gtk/gtk.symbols index 04394206af..b6aaed11db 100644 --- a/gtk/gtk.symbols +++ b/gtk/gtk.symbols @@ -4367,10 +4367,10 @@ gtk_widget_get_mapped gtk_widget_get_support_multidevice gtk_widget_set_support_multidevice gtk_widget_device_is_shadowed -gtk_widget_get_h_align -gtk_widget_set_h_align -gtk_widget_get_v_align -gtk_widget_set_v_align +gtk_widget_get_halign +gtk_widget_set_halign +gtk_widget_get_valign +gtk_widget_set_valign gtk_widget_get_margin_left gtk_widget_set_margin_left gtk_widget_get_margin_right diff --git a/gtk/gtksizerequest.c b/gtk/gtksizerequest.c index e2ada954ae..db7282611a 100644 --- a/gtk/gtksizerequest.c +++ b/gtk/gtksizerequest.c @@ -87,6 +87,33 @@ * width. By following this rule any widget that handles height-for-width * or width-for-height requests will always be allocated at least * enough space to fit its own content. + * + * Often a widget needs to get its own request during size request or + * allocation, for example when computing height it may need to also + * compute width, or when deciding how to use an allocation the widget may + * need to know its natural size. In these cases, the widget should be + * careful to call its virtual methods directly, like this: + * + * Widget calling its own size request method. + * + * GTK_SIZE_REQUEST_GET_IFACE(widget)->get_width(GTK_SIZE_REQUEST(widget), &min, &natural); + * + * + * + * It will not work to use the wrapper functions, such as + * gtk_size_request_get_width(), inside your own size request + * implementation. These return a request adjusted by #GtkSizeGroup + * and by the GtkWidgetClass::adjust_size_request virtual method. If a + * widget used the wrappers inside its virtual method implementations, + * then the adjustments (such as widget margins) would be applied + * twice. GTK+ therefore does not allow this and will warn if you try + * to do it. + * + * Of course if you are getting the size request for + * another widget, such as a child of a + * container, you must use the wrapper APIs; + * otherwise, you would not properly consider widget margins, + * #GtkSizeGroup, and so forth. * * */ @@ -420,6 +447,12 @@ gtk_size_request_get_request_mode (GtkSizeRequest *widget) * This call is specific to height-for-width * requests. * + * The returned request will be modified by the + * GtkWidgetClass::adjust_size_request virtual method and by any + * #GtkSizeGroup that have been applied. That is, the returned request + * is the one that should be used for layout, not necessarily the one + * returned by the widget itself. + * * Since: 3.0 */ void @@ -442,6 +475,12 @@ gtk_size_request_get_width (GtkSizeRequest *widget, * * This call is specific to width-for-height requests. * + * The returned request will be modified by the + * GtkWidgetClass::adjust_size_request virtual method and by any + * #GtkSizeGroup that have been applied. That is, the returned request + * is the one that should be used for layout, not necessarily the one + * returned by the widget itself. + * * Since: 3.0 */ void @@ -465,6 +504,12 @@ gtk_size_request_get_height (GtkSizeRequest *widget, * Retrieves a widget's minimum and natural width if it would be given * the specified @height. * + * The returned request will be modified by the + * GtkWidgetClass::adjust_size_request virtual method and by any + * #GtkSizeGroup that have been applied. That is, the returned request + * is the one that should be used for layout, not necessarily the one + * returned by the widget itself. + * * Since: 3.0 */ void @@ -487,6 +532,12 @@ gtk_size_request_get_width_for_height (GtkSizeRequest *widget, * Retrieves a widget's minimum and natural height if it would be given * the specified @width. * + * The returned request will be modified by the + * GtkWidgetClass::adjust_size_request virtual method and by any + * #GtkSizeGroup that have been applied. That is, the returned request + * is the one that should be used for layout, not necessarily the one + * returned by the widget itself. + * * Since: 3.0 */ void diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index 2de732f923..ddc923763f 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -279,8 +279,8 @@ enum { PROP_TOOLTIP_TEXT, PROP_WINDOW, PROP_DOUBLE_BUFFERED, - PROP_H_ALIGN, - PROP_V_ALIGN, + PROP_HALIGN, + PROP_VALIGN, PROP_MARGIN_LEFT, PROP_MARGIN_RIGHT, PROP_MARGIN_TOP, @@ -871,15 +871,15 @@ gtk_widget_class_init (GtkWidgetClass *klass) GTK_PARAM_READWRITE)); /** - * GtkWidget:h-align + * GtkWidget:halign: * * How to distribute horizontal space if widget gets extra space, see #GtkAlign * * Since: 3.0 */ g_object_class_install_property (gobject_class, - PROP_H_ALIGN, - g_param_spec_enum ("h-align", + PROP_HALIGN, + g_param_spec_enum ("halign", P_("Horizontal Alignment"), P_("How to position in extra horizontal space"), GTK_TYPE_ALIGN, @@ -887,15 +887,15 @@ gtk_widget_class_init (GtkWidgetClass *klass) GTK_PARAM_READWRITE)); /** - * GtkWidget:v-align + * GtkWidget:valign: * * How to distribute vertical space if widget gets extra space, see #GtkAlign * * Since: 3.0 */ g_object_class_install_property (gobject_class, - PROP_V_ALIGN, - g_param_spec_enum ("v-align", + PROP_VALIGN, + g_param_spec_enum ("valign", P_("Vertical Alignment"), P_("How to position in extra vertical space"), GTK_TYPE_ALIGN, @@ -2941,11 +2941,11 @@ gtk_widget_set_property (GObject *object, case PROP_DOUBLE_BUFFERED: gtk_widget_set_double_buffered (widget, g_value_get_boolean (value)); break; - case PROP_H_ALIGN: - gtk_widget_set_h_align (widget, g_value_get_enum (value)); + case PROP_HALIGN: + gtk_widget_set_halign (widget, g_value_get_enum (value)); break; - case PROP_V_ALIGN: - gtk_widget_set_v_align (widget, g_value_get_enum (value)); + case PROP_VALIGN: + gtk_widget_set_valign (widget, g_value_get_enum (value)); break; case PROP_MARGIN_LEFT: gtk_widget_set_margin_left (widget, g_value_get_int (value)); @@ -3077,11 +3077,11 @@ gtk_widget_get_property (GObject *object, case PROP_DOUBLE_BUFFERED: g_value_set_boolean (value, gtk_widget_get_double_buffered (widget)); break; - case PROP_H_ALIGN: - g_value_set_enum (value, gtk_widget_get_h_align (widget)); + case PROP_HALIGN: + g_value_set_enum (value, gtk_widget_get_halign (widget)); break; - case PROP_V_ALIGN: - g_value_set_enum (value, gtk_widget_get_v_align (widget)); + case PROP_VALIGN: + g_value_set_enum (value, gtk_widget_get_valign (widget)); break; case PROP_MARGIN_LEFT: g_value_set_int (value, gtk_widget_get_margin_left (widget)); @@ -4185,8 +4185,10 @@ gtk_widget_queue_shallow_draw (GtkWidget *widget) * and position to their child widgets. * * In this function, the allocation may be adjusted. It will be forced - * to a 1x1 minimum size, and the adjust_size_allocation virtual method - * on the child will be used to adjust the allocation. + * to a 1x1 minimum size, and the adjust_size_allocation virtual + * method on the child will be used to adjust the allocation. Standard + * adjustments include removing the widget's margins, and applying the + * widget's #GtkWidget:halign and #GtkWidget:valign properties. **/ void gtk_widget_size_allocate (GtkWidget *widget, @@ -4569,7 +4571,7 @@ get_span_inside_border_horizontal (GtkWidget *widget, int *width_inside_p) { get_span_inside_border (widget, - aux_info->h_align, + aux_info->halign, aux_info->margin.left, aux_info->margin.right, allocated_outside_width, @@ -4587,7 +4589,7 @@ get_span_inside_border_vertical (GtkWidget *widget, int *height_inside_p) { get_span_inside_border (widget, - aux_info->v_align, + aux_info->valign, aux_info->margin.top, aux_info->margin.bottom, allocated_outside_height, @@ -11484,31 +11486,31 @@ gtk_widget_size_request_init (GtkSizeRequestIface *iface) } /** - * gtk_widget_get_h_align: + * gtk_widget_get_halign: * @widget: a #GtkWidget * - * Gets the value of the #GtkWidget:h-align property. + * Gets the value of the #GtkWidget:halign property. * * Returns: the horizontal alignment of @widget */ GtkAlign -gtk_widget_get_h_align (GtkWidget *widget) +gtk_widget_get_halign (GtkWidget *widget) { g_return_val_if_fail (GTK_IS_WIDGET (widget), GTK_ALIGN_FILL); - return _gtk_widget_get_aux_info_or_defaults (widget)->h_align; + return _gtk_widget_get_aux_info_or_defaults (widget)->halign; } /** - * gtk_widget_set_h_align: + * gtk_widget_set_halign: * @widget: a #GtkWidget * @align: the horizontal alignment * * Sets the horizontal alignment of @widget. - * See the #GtkWidget:h-align property. + * See the #GtkWidget:halign property. */ void -gtk_widget_set_h_align (GtkWidget *widget, - GtkAlign align) +gtk_widget_set_halign (GtkWidget *widget, + GtkAlign align) { GtkWidgetAuxInfo *aux_info; @@ -11516,40 +11518,40 @@ gtk_widget_set_h_align (GtkWidget *widget, aux_info = _gtk_widget_get_aux_info (widget, TRUE); - if (aux_info->h_align == align) + if (aux_info->halign == align) return; - aux_info->h_align = align; + aux_info->halign = align; gtk_widget_queue_resize (widget); - g_object_notify (G_OBJECT (widget), "h-align"); + g_object_notify (G_OBJECT (widget), "halign"); } /** - * gtk_widget_get_v_align: + * gtk_widget_get_valign: * @widget: a #GtkWidget * - * Gets the value of the #GtkWidget:v-align property. + * Gets the value of the #GtkWidget:valign property. * * Returns: the vertical alignment of @widget */ GtkAlign -gtk_widget_get_v_align (GtkWidget *widget) +gtk_widget_get_valign (GtkWidget *widget) { g_return_val_if_fail (GTK_IS_WIDGET (widget), GTK_ALIGN_FILL); - return _gtk_widget_get_aux_info_or_defaults (widget)->v_align; + return _gtk_widget_get_aux_info_or_defaults (widget)->valign; } /** - * gtk_widget_set_v_align: + * gtk_widget_set_valign: * @widget: a #GtkWidget * @align: the vertical alignment * * Sets the vertical alignment of @widget. - * See the #GtkWidget:h-align property. + * See the #GtkWidget:valign property. */ void -gtk_widget_set_v_align (GtkWidget *widget, - GtkAlign align) +gtk_widget_set_valign (GtkWidget *widget, + GtkAlign align) { GtkWidgetAuxInfo *aux_info; @@ -11557,12 +11559,12 @@ gtk_widget_set_v_align (GtkWidget *widget, aux_info = _gtk_widget_get_aux_info (widget, TRUE); - if (aux_info->v_align == align) + if (aux_info->valign == align) return; - aux_info->v_align = align; + aux_info->valign = align; gtk_widget_queue_resize (widget); - g_object_notify (G_OBJECT (widget), "v-align"); + g_object_notify (G_OBJECT (widget), "valign"); } /** @@ -12202,6 +12204,21 @@ gtk_widget_get_has_tooltip (GtkWidget *widget) * * Retrieves the widget's allocation. * + * Note, when implementing a #GtkContainer: a widget's allocation will + * be its "adjusted" allocation, that is, the widget's parent + * container typically calls gtk_widget_size_allocate() with an + * allocation, and that allocation is then adjusted (to handle margin + * and alignment for example) before assignment to the widget. + * gtk_widget_get_allocation() returns the adjusted allocation that + * was actually assigned to the widget. The adjusted allocation is + * guaranteed to be completely contained within the + * gtk_widget_size_allocate() allocation, however. So a #GtkContainer + * is guaranteed that its children stay inside the assigned bounds, + * but not that they have exactly the bounds the container assigned. + * There is no way to get the original allocation assigned by + * gtk_widget_size_allocate(), since it isn't stored; if a container + * implementation needs that information it will have to track it itself. + * * Since: 2.18 */ void @@ -12226,6 +12243,13 @@ gtk_widget_get_allocation (GtkWidget *widget, * Sets the widget's allocation. This should not be used * directly, but from within a widget's size_allocate method. * + * The allocation set should be the "adjusted" or actual + * allocation. If you're implementing a #GtkContainer, you want to use + * gtk_widget_size_allocate() instead of gtk_widget_set_allocation(). + * The GtkWidgetClass::adjust_size_allocation virtual method adjusts the + * allocation inside gtk_widget_size_allocate() to create an adjusted + * allocation. + * * Since: 2.18 */ void diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h index baf77dc14f..36cd35d24f 100644 --- a/gtk/gtkwidget.h +++ b/gtk/gtkwidget.h @@ -266,30 +266,47 @@ struct _GtkWidget /** * GtkWidgetClass: - * @parent_class: - * @activate_signal: - * @set_scroll_adjustments_signal: - * - * activate_signal - * The signal to emit when a widget of this class is activated, - * gtk_widget_activate() handles the emission. Implementation of this - * signal is optional. - * - * - * set_scroll_adjustment_signal - * This signal is emitted when a widget of this class is added - * to a scrolling aware parent, gtk_widget_set_scroll_adjustments() - * handles the emission. - * Implementation of this signal is optional. + * @parent_class: The object class structure needs to be the first + * element in the widget class structure in order for the class mechanism + * to work correctly. This allows a GtkWidgetClass pointer to be cast to + * a GtkObjectClass pointer. + * @activate_signal: The signal to emit when a widget of this class is + * activated, gtk_widget_activate() handles the emission. + * Implementation of this signal is optional. + * @set_scroll_adjustments_signal: This signal is emitted when a widget of + * this class is added to a scrolling aware parent, + * gtk_widget_set_scroll_adjustments() handles the emission. + * Implementation of this signal is optional. + * @adjust_size_request: Convert an initial size request from a widget's + * #GtkSizeRequest virtual method implementations into a size request to + * be used by parent containers in laying out the widget. + * adjust_size_request adjusts from a child widget's + * original request to what a parent container should + * use for layout. The @for_size argument will be -1 if the request should + * not be for a particular size in the opposing orientation, i.e. if the + * request is not height-for-width or width-for-height. If @for_size is + * greater than -1, it is the proposed allocation in the opposing + * orientation that we need the request for. Implementations of + * adjust_size_request should chain up to the default implementation, + * which applies #GtkWidget's margin properties and imposes any values + * from gtk_widget_set_size_request(). Chaining up should be last, + * after your subclass adjusts the request, so + * #GtkWidget can apply constraints and add the margin properly. + * @adjust_size_allocation: Convert an initial size allocation assigned + * by a #GtkContainer using gtk_widget_size_allocate(), into an actual + * size allocation to be used by the widget. adjust_size_allocation + * adjusts to a child widget's actual allocation + * from what a parent container computed for the + * child. The adjusted allocation must be entirely within the original + * allocation. In any custom implementation, chain up to the default + * #GtkWidget implementation of this method, which applies the margin + * and alignment properties of #GtkWidget. Chain up + * before performing your own adjustments so your + * own adjustments remove more allocation after the #GtkWidget base + * class has already removed margin and alignment. */ struct _GtkWidgetClass { - /* The object class structure needs to be the first - * element in the widget class structure in order for - * the class mechanism to work correctly. This allows a - * GtkWidgetClass pointer to be cast to a GtkObjectClass - * pointer. - */ GtkObjectClass parent_class; /*< public >*/ @@ -474,6 +491,8 @@ struct _GtkWidgetClass gboolean keyboard_tooltip, GtkTooltip *tooltip); + /*< public >*/ + void (* adjust_size_request) (GtkWidget *widget, GtkOrientation orientation, gint for_size, @@ -482,6 +501,8 @@ struct _GtkWidgetClass void (* adjust_size_allocation) (GtkWidget *widget, GtkAllocation *allocation); + /*< private >*/ + /* Signals without a C default handler class slot: * gboolean (*damage_event) (GtkWidget *widget, * GdkEventExpose *event); @@ -503,8 +524,8 @@ struct _GtkWidgetAuxInfo gint width; gint height; - guint h_align : 4; - guint v_align : 4; + guint halign : 4; + guint valign : 4; GtkBorder margin; }; @@ -741,11 +762,11 @@ AtkObject* gtk_widget_get_accessible (GtkWidget *wi /* Margin and alignment */ -GtkAlign gtk_widget_get_h_align (GtkWidget *widget); -void gtk_widget_set_h_align (GtkWidget *widget, +GtkAlign gtk_widget_get_halign (GtkWidget *widget); +void gtk_widget_set_halign (GtkWidget *widget, GtkAlign align); -GtkAlign gtk_widget_get_v_align (GtkWidget *widget); -void gtk_widget_set_v_align (GtkWidget *widget, +GtkAlign gtk_widget_get_valign (GtkWidget *widget); +void gtk_widget_set_valign (GtkWidget *widget, GtkAlign align); gint gtk_widget_get_margin_left (GtkWidget *widget); void gtk_widget_set_margin_left (GtkWidget *widget, diff --git a/tests/testadjustsize.c b/tests/testadjustsize.c index b0389d9a81..c13d9d8c73 100644 --- a/tests/testadjustsize.c +++ b/tests/testadjustsize.c @@ -291,21 +291,21 @@ enum_to_string (GType enum_type, } static GtkWidget* -create_aligned (GtkAlign h_align, - GtkAlign v_align) +create_aligned (GtkAlign halign, + GtkAlign valign) { GtkWidget *widget; char *label; label = g_strdup_printf ("h=%s v=%s", - enum_to_string (GTK_TYPE_ALIGN, h_align), - enum_to_string (GTK_TYPE_ALIGN, v_align)); + enum_to_string (GTK_TYPE_ALIGN, halign), + enum_to_string (GTK_TYPE_ALIGN, valign)); widget = create_widget_visible_border (label); g_object_set (G_OBJECT (TEST_WIDGET (widget)), - "h-align", h_align, - "v-align", v_align, + "halign", halign, + "valign", valign, NULL); return widget; -- 2.30.2